home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / audio / alConnect.z / alConnect
Encoding:
Text File  |  2002-10-03  |  9.6 KB  |  265 lines
  1.  
  2.  
  3.  
  4. aaaallllCCCCoooonnnnnnnneeeecccctttt((((3333ddddmmmm))))                                                  aaaallllCCCCoooonnnnnnnneeeecccctttt((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      alConnect - connect two audio I/O resources
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiioooo....hhhh>>>>
  13.  
  14.      iiiinnnntttt aaaallllCCCCoooonnnnnnnneeeecccctttt((((iiiinnnntttt ssssoooouuuurrrrcccceeee,,,, iiiinnnntttt ddddeeeesssstttt,,,, AAAALLLLppppvvvv ****pppprrrrooooppppssss,,,, iiiinnnntttt nnnnpppprrrrooooppppssss))))
  15.  
  16. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR
  17.      _s_o_u_r_c_e   is the source resource.
  18.  
  19.      _d_e_s_t     is the destination resource.
  20.  
  21.      _p_r_o_p_s    is a parameter/value list of desired properties for the
  22.               connection (see aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) for more information on
  23.               parameter/value lists).
  24.  
  25.      _n_p_r_o_p_s   is the number of parameter/value pairs in the list _p_r_o_p_s.
  26.  
  27. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  28.      An audio _c_o_n_n_e_c_t_i_o_n moves audio data from one audio I/O resource to
  29.      another. For example, when an application opens an audio input port, the
  30.      audio system creates a connection from an input device to the input port.
  31.      See aaaallllRRRReeeessssoooouuuurrrrcccceeeessss((((3333ddddmmmm)))) for information on resources in general.
  32.  
  33.      aaaallllCCCCoooonnnnnnnneeeecccctttt creates a connection from the resource _s_o_u_r_c_e to the resource
  34.      _d_e_s_t. aaaallllCCCCoooonnnnnnnneeeecccctttt can connect a port to a device, a device to a port, or a
  35.      device to a device; port-to-port connections are not supported at this
  36.      time. Other types of resources cannot be connected.
  37.  
  38.      In addition, there are certain constraints on the directions of _s_o_u_r_c_e
  39.      and _d_e_s_t. _s_o_u_r_c_e must be either an input device or an output port. _d_e_s_t
  40.      must be either an output device or an input port.
  41.  
  42.      A connection performs certain operations on the audio data.  These
  43.      operations are given by the properties list _p_r_o_p_s.  See below for the
  44.      currently supported properties. If _n_p_r_o_p_s is 0, the connection will be
  45.      given a default set of properties.
  46.  
  47.      If a connection already exists between the given _s_o_u_r_c_e and _d_e_s_t,
  48.      aaaallllCCCCoooonnnnnnnneeeecccctttt will return the resource ID of the existing connection and set
  49.      the given properties _p_r_o_p_s on that connection.
  50.  
  51.      Note that by default, connections persist after the application which
  52.      creates them exits. In order to remove the connection, you must
  53.      explicitly call aaaallllDDDDiiiissssccccoooonnnnnnnneeeecccctttt((((3333ddddmmmm)))), or create the connection with the
  54.      AL_ASSOCIATE property.
  55.  
  56.      Only one property is currently supported for connections, AL_ASSOCIATE,
  57.      which allows you to associate a connection with a particular port.
  58.      AL_ASSOCIATE takes as its value the resource ID of a port (see
  59.      aaaallllGGGGeeeettttRRRReeeessssoooouuuurrrrcccceeee((((3333ddddmmmm))))).  When the port is destroyed, the connection is
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaallllCCCCoooonnnnnnnneeeecccctttt((((3333ddddmmmm))))                                                  aaaallllCCCCoooonnnnnnnneeeecccctttt((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      destroyed as well. This allows an application to create a connection
  75.      which is guaranteed to go away when the application goes away.
  76.  
  77. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  78.      The following simple program takes two device names as command-line
  79.      arguments and creates a connection between them.  This connection will
  80.      persist after the program exits.
  81.  
  82.           main(int argc, char **argv)
  83.           {
  84.                int fd;
  85.                int src, dest;
  86.                int id;
  87.  
  88.                if (argc != 3) {
  89.                   printf("usage: %s <src> <dest>\n",argv[0]);
  90.                   exit(-1);
  91.                }
  92.  
  93.                /* Find the source resource */
  94.                src = alGetResourceByName(AL_SYSTEM, argv[1], AL_DEVICE_TYPE);
  95.                if (!src) {
  96.                   printf("invalid device %s\n", argv[1]);
  97.                   exit(-1);
  98.                }
  99.  
  100.                /* Find the destination resource */
  101.                dest = alGetResourceByName(AL_SYSTEM, argv[2], AL_DEVICE_TYPE);
  102.                if (!dest) {
  103.                   printf("invalid device %s\n", argv[2]);
  104.                   exit(-1);
  105.                }
  106.  
  107.                /* Attempt to connect them */
  108.                if ((id = alConnect(src, dest, 0, 0))<0) {
  109.                   printf("connect failed: %s\n",alGetErrorString(oserror()));
  110.                }
  111.                printf("connection ID is %d\n",id);
  112.           }
  113.  
  114.  
  115.      The following code fragment creates a connection which goes away when a
  116.      port goes away. Since the port is tied to the application, this
  117.      connection does not persist after the application exits.  This particular
  118.      example creates a port which does not actually do audio; it is connected
  119.      to no audio device. We also give it a minimal queue size so that it
  120.      consumes few audio resources.
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. aaaallllCCCCoooonnnnnnnneeeecccctttt((((3333ddddmmmm))))                                                  aaaallllCCCCoooonnnnnnnneeeecccctttt((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.                ALport p;
  141.                ALconfig c;
  142.                ALpv pv;
  143.                int id, src, dest;
  144.  
  145.                /* code here to set src & dest */
  146.  
  147.                [...]
  148.  
  149.                /* create a config structure */
  150.                c = alNewConfig();
  151.                if (!c) {
  152.                printf("alNewConfig failed: %s0,alGetErrorString(oserror()));
  153.                exit(-1);
  154.                }
  155.  
  156.                /* set the config so the port does no audio */
  157.                alSetDevice(c, AL_NULL_RESOURCE);
  158.                alSetQueueSize(c, 100);
  159.  
  160.                /* now open a port using the config */
  161.                p = alOpenPort("null port","r",c);
  162.                if (!p) {
  163.                printf("alOpenPort failed: %s0,alGetErrorString(oserror()));
  164.                exit(-1);
  165.                }
  166.  
  167.                /* Attempt to connect src & dest. We assume that these are set
  168.                to valid resource IDs. */
  169.  
  170.                pv.param = AL_ASSOCIATE;
  171.                pv.value.i = alGetResource(p);
  172.  
  173.                if ((id = alConnect(src, dest, &pv, 1))<0) {
  174.                   printf("connect failed: %s\n",alGetErrorString(oserror()));
  175.                }
  176.                printf("connection ID is %d\n",id);
  177.  
  178.                /* now, when we close the port, or the application exits (also
  179.                closing the port), the connection will automatically go away */
  180.                [...]
  181.  
  182.  
  183.  
  184. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  185.      If successful, aaaallllCCCCoooonnnnnnnneeeecccctttt returns the resource ID of the connection.  It
  186.      returns -1 if the connection fails, and sets an error code which can be
  187.      retrieved with oooosssseeeerrrrrrrroooorrrr((((3333CCCC)))).
  188.  
  189.      aaaallllCCCCoooonnnnnnnneeeecccctttt can fail for the following reasons:
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. aaaallllCCCCoooonnnnnnnneeeecccctttt((((3333ddddmmmm))))                                                  aaaallllCCCCoooonnnnnnnneeeecccctttt((((3333ddddmmmm))))
  203.  
  204.  
  205.  
  206.      AAAALLLL____BBBBAAAADDDD____RRRREEEESSSSOOOOUUUURRRRCCCCEEEE
  207.           _s_o_u_r_c_e or _d_e_s_t is an invalid resource.
  208.  
  209.      AAAALLLL____BBBBAAAADDDD____DDDDEEEEVVVVIIIICCCCEEEE____AAAACCCCCCCCEEEESSSSSSSS
  210.           The audio system is not present or improperly configured.
  211.  
  212.      AAAALLLL____BBBBAAAADDDD____PPPPVVVVBBBBUUUUFFFFFFFFEEEERRRR
  213.           _p_r_o_p_s is invalid and _n_p_r_o_p_s is nonzero.
  214.  
  215.      AAAALLLL____BBBBAAAADDDD____BBBBUUUUFFFFFFFFEEEERRRRLLLLEEEENNNNGGGGTTTTHHHH
  216.           _n_p_r_o_p_s is less than zero.
  217.  
  218. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  219.      oserror(3C), alIntro(3dm), alGetParams(3dm), alDisconnect(3dm)
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.